Crate onig

Expand description

This crate provides a safe wrapper around the Oniguruma regular expression library.

Examples

use onig::Regex;

let regex = Regex::new("e(l+)").unwrap();
for (i, pos) in regex.captures("hello").unwrap().iter_pos().enumerate() {
    match pos {
         Some((beg, end)) =>
             println!("Group {} captured in position {}:{}", i, beg, end),
         None =>
             println!("Group {} is not captured", i)
    }
}

There are two basic things you can do with a Regex pattern; test if the pattern matches the whole of a given string, and search for occurences of the pattern within a string. Oniguruma exposes these two concepts with the match and search APIs.

In addition two these two base Onigurma APIs this crate exposes a third find API, built on top of the search API.

let pattern = Regex::new("hello").unwrap();
assert_eq!(true, pattern.find("hello world").is_some());
assert_eq!(false, pattern.is_match("hello world"));

The Match API

Functions in the match API check if a pattern matches the entire string. The simplest of these is Regex::is_match. This retuns a true if the pattern matches the string. For more complex useage then Regex::match_with_options and Regex::match_with_encoding can be used. These allow the capture groups to be inspected, matching with different options, and matching sub-sections of a given text.

The Search API

Function in the search API search for a pattern anywhere within a string. The simplist of these is Regex::find. This returns the offset of the first occurence of the pattern within the string. For more complex useage Regex::search_with_options and Regex::search_with_encoding can be used. These allow capture groups to be inspected, searching with different options and searching within subsections of a given text.

The Find API

The find API is built on top of the search API. Functions in this API allow iteration across all matches of the pattern within a string, not just the first one. The functions deal with some of the complexities of this, such as zero-length matches.

The simplest step-up from the basic search API Regex::find is getting the captures relating to a match with the Regex::captures method. To find capture information for all matches within a string Regex::find_iter and Regex::captures_iter can be used. The former exposes the start and end of the match as Regex::find does, the latter exposes the whole capture group information as Regex::captures does.

The `std::pattern` API

In addition to the main Oniguruma API it is possible to use the Regex object with the std::pattern API. To enable support compile with the std-pattern feature. If you’re using Cargo you can do this by adding the following to your Cargo.toml:

[dependencies.onig]
version = "1.2"
features = ["std-pattern"]

Structs

CaptureTreeNode

Capture Tree Node

CaptureTreeNodeIter

Captures iterator

Captures

Captures represents a group of captured strings for a single match.

EncodedBytes

Byte Buffer

Error

This struture represents an error from the underlying Oniguruma libray.

FindCaptures

An iterator that yields all non-overlapping capture groups matching a particular regular expression.

FindMatches

An iterator over all non-overlapping matches for a particular string.

MatchParam

Parameters for a Match or Search.

MetaCharType

Syntax meta character types

Regex

This struct is a wrapper around an Oniguruma regular expression pointer. This represents a compiled regex which can be used in search and match operations.

RegexOptions

Regex parsing and compilation options.

RegexSplits

Yields all substrings delimited by a regular expression match.

RegexSplitsN

Yields at most N substrings delimited by a regular expression match.

Region

Represents a set of capture groups found in a search or match.

SearchOptions

Regex evaluation options.

SubCaptures

An iterator over capture groups for a particular match of a regular expression.